Transfer to Bank

Note: Before using this API, please use Payout Capability API to retrieve the supported payout methods and which parameters need to be passed for each payout method. If the currency of received amount is not AED, please use the Rate Calculator API to get the latest exchange rate.

API URL

• UAT : https://uat.test2pay.com/sgs/api/transfer/placeTransferToBankOrder
• Production : https://api.payby.com/sgs/api/transfer/placeTransferToBankOrder

Request

Http Header

Attributes

• Content-Language String

  • Language in which the response message will be used.
  • Currently, only English is supported.
  • Example value: en
  • Maximum length: 10

• Content-Type String Required

  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/<format> (e.g., application/json)
  • Example value: application/json

• sign String Required

  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.

• Partner-Id String Required

  • Merchant ID of your account.
  • Example value: 200001200101
  • Maximum length: 12

Http Body

• requestTime Timestamp Required

  Request time of the order. If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.

  Example value: 1581493898000

• bizContent Object

  Attributes

  • merchantOrderNo String Required

    • Unique identifier for the merchant's order.
    • Example value: Me23484

  • holderName String Required

    • Name of the beneficiary. Transmitted securely (encrypted).
    • Example value: Bruce Lee

  • iban String

    • International Bank Account Number. Transmitted securely (encrypted).
    • Example value: -

  • swiftCode String

    • Improves accuracy if provided.
    • Example value: ARABAEADDER

  • beneficiaryAddress String

    • Transmitted securely.
      If the bank account is personal, this field is required.
      The combined length of holderName and beneficiaryAddress must not exceed 140 characters, or the transfer may fail.
    • Example value: Liwa Street off Khaliffa Street

  • amount Money Required

    • Payment amount for the transaction.
    • Example value: 12.34

  • memo String Required

    • Remarks or notes for the payment.
    • Example value: Bonus

  • notifyUrl String

    • URL for receiving backend notifications.
    • Example value: -

  • accountNo String

    • Transmitted securely (available since v2.1).
    • Example value: 2000000000001

  • networkCode String

    • Defaults to LOCAL (available since v2.1).
    • Example value: LOCAL

  • bankName String

    • Name of the bank.
    • Example value: (empty)

  • countryCode String

    • Defaults to AE (available since v2.1).
    • Example value: AE

  • cityCode String

    • Available since v2.3.
    • Example value: (empty)

  • fundoutCurrencyCode String

    • Defaults to AED (available since v2.1).
    • Example value: AED

  • fedwireCode String

    • Fedwire code (available since v2.1).
    • Example value: -

  • branchName String

    • Name of the bank branch.
    • Example value: -

  • intermediaryBank String

    • Intermediary bank code (available since v2.1).
    • Example value: -

  • beneficiaryType String

    • Defaults to IBAN (available since v2.1).
    • Example value: IBAN

  • purposeCode String

    • Code indicating the purpose of the transaction.
    • Example value: COM

Beneficiary Type

Required and optional fields for different beneficiary types.

	holderName	iban	swiftCode	beneficiaryAddress	accountNo	bankName	fedwireCode	branchName	intermediaryBank	purposeCode
IBAN	Required	Required	Optional	Required	Forbidden	Optional	Forbidden	Optional	Optional	Optional
BBAN	Required	Forbidden	Required	Required	Required	Optional	Forbidden	Optional	Optional	Optional
FED_WIRE	Required	Forbidden	Forbidden	Required	Required	Optional	Required	Optional	Optional	Optional

Request Sample

// Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "S5Wr6x9Po1SX3nm4kRJyTueUMbnmsPGMlMjc3PcoyNyP0G5BuRAwauYjTJLeto6Bu1+893zCGmj201mjrvcXP4v/uMzQxRav5PBMp9VuQ+3dOFGclQAwr8cFAKuBDHhGAAkw1iVpdC8ZZLGl/jRUv3PCiZh6VyOLnrK7ZIevB/TetQSzCmN1xDIQo8mpDYz7YY/jSzYBnD17ePvkr4qQOWNUh7FF2nd29lo9KOQl5tJVoqT/D+PVSlZeuGr+wxBYCAyGqbVXXSAGcwF1egF6ISLJ29jpHcX/LACXxF/uf5cdzbudwPB2X0wtRw9WnowY3RUq34sidoF4DIShXVFHAg=="
}

// Http Body
{
    "bizContent":{
        "amount":{
            "amount":0.1,
            "currency":"AED"
        },
        "beneficiaryAddress":"ImHDvH9bcOzm1dzlywKk2xZdQzGIuZqm1gxvt+CG4N3S4ShI1WfDuEzkTgx/qjS1LovKsztFs35TbORQ84LaKo9UyzBjhrfqaUkGxcTWc9xo2H/x4oGX4oTt+p5LCeKWciyeNITK+J11cEoppCCvjhwXK64b7cAuIgm+YTFs2P/65bD/SGahWht9tg8aDqNDltZs/JLhjzFSvz65ZpREeKPM9f2eth0tnB2eWaLZEW5JZM+Y9lCD2nvFkTBMaEJFRAoTMiHPGba1CMm0SwEkjYhZhfSDfqLyZ1+IhxOz2xqjgwJi4noxd9pg5yRX/qzLMdZBT7rF+r1tj5Ji4ATDXw==",
        "holderName":"nP7Yq9e+AJQVbhMtiAcUU0wUZtL5yAb2w95D1Xjvw+FvP4dMrAGQP4mEQT3EQHcl+jAVAS0mej3NJYAVa9ZemWtACRFiUV9c9ub0v8lYtoooQ8AMRMZeSGDCieVTTHkq14Zfg/Xtymx5Pk2PHwhb++oQ5GYPLkoVSQZlBwqhTBiyywLkix03kVwazNxNI40QWjZ9mR+dUlGPASVU5RaOKXd/DNFuETRCUKXc10772kK+e2Bp1G3wmXY+jFQTJPwU38ikDrbilVmJ445LkQzA9MtWwVeh6bRROB2Ei7rBgr3LmTSiQhM6nBeJmNIX3xHf1L0i2sSIKuioaU64M3D6jw==",
        "iban":"hnfMFYm0GZlIvi9fKOkPG1Yys7P3q7PeQ+lhw1umoPCptP59rCUzFxEcpsu9IGJY6HrGVgLgzlpfoFhfDQG5rwJewhjxGcCx9H2ywzBEogVjpquOIVLF4WCD5CZZE3bjqr27Cy3CyKvwCfxC7HCBgiPZAdwM2oHdvJCkHBeUDL58aGBaJnzPiBetLXDyrh4t0od6vrF26eoh/MseaiXnFrykBA9oQZsU+1HZP5FoMjyqDZVFw/4N7Py8dQ3gmw/Y2HMdZvQIUHIi7Nc9UiF9YxTyV7YdVLMSZGwTwObVTYrD2d73bkQ4bFr7Hctu6ERJYutrd266AiSaHtGf60tcZg==",
        "memo":"Bonus",
        "merchantOrderNo":"d98db926-5ad1-4046-9c51-3c9b7283b44e",
        "networkCode":"LOCAL",
        "notifyUrl":"http://yoursite.com/api/notification",
        "swiftCode":"BBMEAEAD"
    },
    "requestTime":1646277045337
}

Response

Http Header

sign String Required

When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.

Http Body

head

Attributes

• applyStatus Enum Required

  • The result of the request. Possible values:
    • SUCCESS: Application successful.
    • FAIL: Application failed. Check the code and msg for the exact reason.
    • ERROR: Application error. Signature verification failed. Ensure the private key used for the signature and the public key uploaded on the PayBy portal are a valid key pair.

• code String Required

  • Response code.
  • Example value: 0
  • Maximum length: 10

• msg String

  • Description of the response code.
  • Maximum length: 200

• traceCode String

  • Internal code for locating the error.

body

Notice

Body is returned only when applystatus = success, and code = 0. If applystatus = error or failed; or applystatus = success, code !=0 , that indicates an error. Please check errors and try again.

• transferToBankOrder Object

  Attributes

  • requestTime Timestamp Required

    • Time the request was initiated.
    • Example value: 1581493898000

  • merchantOrderNo String Required

    • Unique identifier for the merchant's order.
    • Example value: S10000

  • orderNo String Required

    • Unique identifier for the PayBy transaction.
    • Example value: O1000

  • product String Required

    • Name of the product or service.
    • Example value: Transfer To Bank

  • status String Required

    • Current status of the order.
    • Example value: -

  • paymentInfo TransferToBankPaymentInfo

    • Detailed information about the payment processing, especially related to fees and timing.

    • Example value:

      {
        "arrivalTime": 1585133416000,
        "payerFeeAmount": {
          "amount": 0,
          "currency": "AED"
        }
      }

    • payerFeeAmount Money

      • The fee charged to the sender (payer), including amount and currency.
      • Example value: -

    • arrivalTime Timestamp (milliseconds, 3-digit precision)

      • Timestamp when the funds were expected to arrive or did arrive.
      • Example value: 1585133416000

  • amount Money Required

    • Transaction amount.
    • Example value: (empty)

  • holderName String Required

    • SHA-256 hash of the original name.
    • Example value: (empty)

  • Iban String Required

    • SHA-256 hash of the original IBAN.
    • Example value: (empty)

  • swiftCode String

    • SWIFT code of the beneficiary bank.
    • Example value: (empty)

  • memo String

    • Remarks or notes for the payment.
    • Example value: (empty)

  • notifyUrl String

    • URL for backend notifications.
    • Example value: (empty)

  • failDes String

    • Reason for order failure.
    • Example value: -

  • beneficiaryAddress String

    • SHA-256 hash of the original address.
    • Example value: (empty)

  • bankReference String

    • Reference number associated with the bank.
    • Example value: (empty)

  • fundoutAmount Money

    • Amount credited to the beneficiary.
    • Example value: (empty)

  • rate BigDecimal

    • Exchange rate used for the transaction.
    • Example value: (empty)

  • networkCode String Required

    • Financial network used.
    • Example value: LOCAL

  • countryCode String

    • Country code of the beneficiary bank.
    • Example value: -

  • bankName String

    • Name of the beneficiary bank.
    • Example value: -

  • fedwireCode String

    • Fedwire account code.
    • Example value: -

  • intermediaryBank String

    • SWIFT code of the intermediary bank.
    • Example value: -

  • branchName String

    • Name of the bank branch.
    • Example value: (empty)

  • beneficiaryType String Required

    • Type of beneficiary account.
    • Example value: IBAN

  • purposeCode String

    • Code indicating the purpose of the transaction.
    • Example value: COM

Response Sample

// Http Header
{
    "sign": "Yv+C2lOQmfERdm5GF9b2V4Y98HmX/6CFyconeOW36AoPqcb7InRcP9E5GnvJLfMoCScuNP4FBdJ5tJpL0A7yPHUMfxARi05jFRSMG97JJazDbWTbRkNM1ZupmTubhUvxvRCgvJp1k0c5yrHph+F+++W5eYho92xnkNgd62BS27i0iDRGzGSmsaPpK7MFcdlvnbbnmDZZJ0LH6RhYiJLYKl+znllQx3jNfCRjV28o22FZ35Q43mZTsS4uAZWbZ/KfaqWoV3sN62Cjj8DSg3mD6GCGWSVbxLq58DUxAq+6GwJ7Gj0Dc9nMXP3gnFW7dodQ9AjL2iHnH6Zh1Pw2D5/ung=="
}

// Http Body
{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "0837"
    },
    "body":{
        "transferToBankOrder":{
            "merchantOrderNo":"e24ef58b-a07f-475a-9716-daf5026a8e8e",
            "orderNo":"131646278513003023",
            "status":"CREATED",
            "holderName":"7b4d8739a0ef0284ba0faf9b79002e3d3096a09be85ae9b503d89bd2fdc2a583",
            "iban":"09599cc57d9126a7759dc4b5d0866eb95c2dfbcf02812a94a5c1c0937cccbfc8",
            "swiftCode":"BBMEAEAD",
            "amount":{
                "amount":0.1,
                "currency":"AED"
            },
            "notifyUrl":"http://yoursite.com/api/notification",
            "memo":"Bonus",
            "requestTime":1646278513375,
            "product":"Transfer To Bank",
            "paymentInfo":{
                "payerFeeAmount":{
                    "amount":5,
                    "currency":"AED"
                },
                "arrivalTime":1646278514000
            },
            "beneficiaryAddress":"ec36f7ed0f1095595da9a506c1cb352c9b89b69c4ceb2c562128c7241661afde",
            "networkCode":"LOCAL"
        }
    }
}

Status Code

Status	Description
CREATED	Created
SUCCESS	Successful
FAILURE	Failed
BANK_FAIL	Bank Rejected

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success
400	INVALID_PARAMETER	Parameter error	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too early compared to current	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too late compared to current	Adjust request time
402	RATE_LIMIT_REJECT	Requests are too frequent	Reduce request frequency
403	UNAUTHORIZED	API not authorized	Contact PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy, try again later
504	SERVICE_TIMEOUT	Service timeout	Try again later
601	RISK_FAIL	Risk control verification failed	Adjust business logic
62002	ORDER_FAILURE	Order has failed	Adjust merchant order number
62016	MERCHANT_ORDER_NO_EXIST	Same order number with different business params	Adjust order number
62026	PRODUCT_IS_NOT_APPLIED	Product not applied	Apply for the product
62028	ORDER_SUCCESS	Order already successful	Adjust merchant order number
62029	ORDER_CREATED	Order already created	Adjust merchant order number
62094	THE_ENTERED_COUNTRY_CODE_IS_INVALID	Country code validation failed	Adjust request parameters
62095	THE_ENTERED_CITY_CODE_IS_INVALID	City code validation failed	Adjust request parameters